TreeGrid Tree Tutorial
1. Row tree
Expanding and collapsing rows
-
The tree is shown when defined Cfg attribute
MainCol
. It specifies column name, where the tree (expand / collapse buttons) is shown.
-
Creating row tree
Only variable rows can be shown in tree.
-
The rows can be placed into tree directly in input data by nesting the <I> tags.
-
Or the tree can be created automatically by Grouping feature. It is demonstrated in next example.
-
Or the two methods can be used both together, some rows can be nested by default and they can be still grouped to create deeper tree.
-
The initial state of the parent rows is set by their
Expanded
attribute.
-
To restrict collapsing (or expanding) the row's children, set
CanExpand
='0'.
-
To show custom expand / collapse icon for any row or row level use row attribute TreeIconX, where X is number 0 - 5 for given icon and state:
0 – not expandable, 1 – last not expandable, 2 – expand (+), 3 – last expand (+), 4 – collapse (-), 5 – last collapse (-).
-
The expand / collapse button can be shown also in other column than the main column by Button='Expand' or Icon='Expand'.
To hide the expand / collapse button in the main column in this case you can set CanExpand='2'.
If state of this button can be changed by another action (e.g. by Expand all or click to another button), the cell should be refreshed, usually in OnExpand API event.
-
It is possible to hide tree lines by Cfg attribute NoTreeLines='1'.
It is possible to hide the root tree in case the first level rows should not be expanded by Cfg attribute HideRootTree='1'.
For small grids it is possible to save the Expanded state of all rows to cookies (by their ids) by Cfg attribute SaveExpanded='1'
-
To scroll to show all parent's children when the parent is expanded, set Cfg attribute NoScrollAfterExpand='0'.
-
To the row ids can be automatically their parent to be unique withint the whole grid.
For this behavior set Cfg attribute FullId
='1'.
The ids are merged together by '$'.
-
API
-
In API every row has set its Level attribute. It is 0 for root rows, 1 for first level rows and so on. For page it is -1.
-
On every expand or collapse is called OnExpand API event.
-
The row can be expanded by method Expand, collapsed by Collapse.
All rows can be expanded by method ExpandAll, collapsed by CollapseAll.
Expanding all rows has various settings, because there are various issues, e.g. in server paging it could lock grid by expanding too many rows.
-
Tree in different columns without nesting
-
It is possible also to expand different rows in different columns.
In this case the rows don't need to be nested in tree, you can just specify which rows will be shown/hidden by which expand button.
It is possible to use both ways (rows in tree and hiding / showing rows) in the same grid.
-
This way is slower than row tree, because the rows are shown / hidden one by one.
-
Define
Button='Expand'
or Icon='Expand'
in the selected cell and by cell attribute ExpandRows
specify the rows (by comma separarated list of their ids) that will be shown / hidden by clicking to that button.
-
It is even possible to let more buttons (in the same or even different row) to control visibility of the same rows.
You can set row attribute ExpandLevel to specify how many expand buttons must be turned on to show the row.
It controls also initial state if some buttons are already expanded on start.
-
By API you can expand / collapse these rows by ExpandCell method and check if the cell is expanded by IsCellExpanded
-
In the same way can be controlled also column visibility, see the next tutorial 2. Column tree.
-
Custom
checkbox in tree
Show checkbox to check / uncheck row in main column by Icon='Check'. Checkbox in parent row shows state of its child checkboxes.
After a user changes some checkbox state, the other parent and child checkboxes are updated too.
The checkbox value is stored in attribute XXXChecked, where XXX is the (main) column where the checkbox is shown.
The checkbox meaning / function is custom and TreeGrid does not use it for any its action.
To upload this value to server, define new hidden column to server as <C Name='XXXChecked' Visible='0' CanHide='0'/>.